Copyright: Copyright © 1995 Kinetic Software
Citation: Copyright © 1995 Kinetic Software


Contents

The KSCalendar component is a graphical component that allows users to select and manipulate dates visually.  The KSCalendar has a fully customizable appearance as well as 70+ properties that allow a software designer to control almost every facet of the calender's functions.

KSCalendar introductory pricing ends on August 1, 1995!  Pick up the best calendar component for Delphi now and save!

The following topics are available in this help file:

How Do I Purchase The KSCalendar?

Published Properties

Public Properties

Methods

Events

Owner Draw Information

Keyboard Control

International Support

Contacting Kinetic Software


Properties Reference

Any KSCalendar properties you can't find below are standard Delphi properties that can be looked up in the Delphi help system.  If you have any properties or features you would like to see please let us know!

Custom Properties:

AutoSizeControlBar	Boolean

Use this property when you are presenting the user with a re-sizable calendar (on a form with the Align property set to alClient for example).  If True the proportion of the control bar height to the height of the calendar will remain constant.  If False the control bar height will remain constant (as set with ControlBarHeight)

BackColor	TColor

The back color is the color that appears behind the day text and the day border (if you are showing it).

Border	Boolean

Determines if the control will draw a thin black frame around the entire calendar.

BorderBevel	Integer

This is the bevel width around the edges of the calendar.  Legal values are from 0 (2D) to 5.  If you choose a larger bevel size you might have to tweak the margin value a little to improve the look of the calendar.

BorderColor	TColor

This is the color of the border (See Border Property) around the calendar.

CalendarColor	TColor

This is the surface color of the calendar.

CellBevel	Integer

This is the bevel width around the edges of the day cells.  Legal values are from 0 (2D) to 5.  If you choose a larger bevel size you might have to increase the size of the calendar to improve the look of the calendar.

ControlBarHeight	Integer

The height of the control bar in pixels.  See the Glyph properties for notes on adjusting this height to suit custom bitmaps.

ControlBarHints	Boolean

Determines whether the control bar will show hints to the user.

ControlBarHintText	TStringList

Use this property to adjust the hint text for the control bar.  KSCalendar will only utilize the first 4 strings you enter here (6 if you are using the advanced control bar).  You can also use this property to help internationalize the calendar (see International Support).  If you are switching control bar styles a lot it is advisable to make sure that there are always 6 strings available to be used as hints!!

ControlBarPosition	Enumerated (cbTop, cbBottom)

The control bar can be placed at the bottom of the component or just below the title (month and year text line).

ControlBarStyle	Enumerated (cbsNone, cbsNormal,cbsAdvanced)

This determines whether or not the calendar will display an integrated control car for selecting the months and years.  Most calendar controls force you to use separate button to scroll months and years.  The KSCalendar integrates these function onto a control bar for quick and easy access.  If you show the control bar you can use the default bitmaps or load your own custom glyphs.  The control bar will also show hints if you set the ControlBarHints property to true.

The advanced control bar (cbsAdvanced) offers you two extra control bar buttons that you can use.  The two buttons fire the custome events: OnFunction1Click and OnFunction2Click.  Think of these two buttoms as "programmable".  For example you can use these two buttons when you are building a "popup" KSCalendar (see DEMO.PAS for a sample popup).

Date	TDateTime	Read Only

This is the main date property of the KSCalendar.  This property reflects the calendar's currently selected date.  Note: This is a read only property ... if you want to set the calendar's date use the public method SetDate.

DateText	TCaption	Read Only

This property contains the date as a formatted string.  The formatting is controlled by the DateFormatString property (below).

DateFormatString	TCaption

Enter the format string you would like to use to output text to the DateText property (above).  For more information on how to use this property see the FormatDateTime function in Delphi.  The KSCalendar uses the same formatting protocol.

Day	Integer

Contains the currently selected calendar day.  Values will range from 1 to 31.

DayNumber	Integer

This property stores the day number of the year.  For example if the calendar date (see Date property) is January 1, 1995...DayNumber will be 1.  If the date is December 31, 1990 then the DayNumber will be 365 (or 366 if 1990 was a leap year).

DayRowHeight	Integer

This is the height of the area of the rectangle that contains the day headings (S M T W T F S).  You can increase this value if you plan to use a larger font for the day headings.  Setting this value to 0 is the same as setting ShowDayRow to False.

DayTextVertPos	Enumerated (vTop, vCenter, vBottom)

DayTextHorzPos	Enumerated (hLeft, hCenter, hRight)

These two properties allow you to designate the position of the DayText (day numbers) in each day cell.  Their are 9 different combinations possible ranging from top left to bottom right.

DayTitleLetters	Integer

This property controls how many characters the calendar will use to display the day titles.  A setting of 1 would produce S M T W T F S, a setting of 2 would produce Su Mo Tu We Th Fr Sa.  A seeting of 9 of produce the full day titles.

DayTitles	TStringList

Use this property to change the text displayed as DayTitles.  (see International Support)

FontMonth	TFont

FontYear	TFont

FontDay	TFont

FontDayTitle	TFont

FontHighLight	TFont

These font properties will allow you select an independent font for each of the textual elements of the calendar.  Using the font property editor you can select the style, color, size and font name.  Please note that if you do select a larger font you might want to increase the dimensions of the calendar to suit the font (or increase the TitleHeight, DayRowHeight etc.)

ForeColor	TColor

This property is used when the calendar is in 2D mode (Ctl3D = False).  It reflects the color of the grid lines separating the day cells.

Gap	Integer

This property assists in the internal spacing of the calendars parts.  Try experimenting with this value to see the results.  It is used to set the amount of space between adjoining regions on the calendar (like the TitleBar and the DayRowBar).

GlyphFunction1	TBitmap

GlyphFunction2	TBitmap

GlyphLastMonth	TBitmap

GlyphNextMonth	TBitmap

GlyphLastYear	TBitmap

GlyphNextYear	TBitmap

These bitmap properties allow you to load custom bitmaps into each of the control bar buttons.  The bitmaps that come with KSCalendar are a bit dull but you can spice up your calendar with some custom bitmaps.  Please not that these bitmaps (glyphs) are not sizable.  They must match up with the size of the control bar (see ControlBarHeight) to look their best.

HighlightBackColor	TColor

This is the color that appears behind the currently selected (highlighted) day.  Combine this property with FontHighLight to customize the appearance of the selected date.

Margin	Integer

This value is the distance between the edge (border) of the calendar and the calendar contents.  It applies to all four sides of the calendar and can be used to adjust the position of the internal elements (month text, year text, day cells etc.) in relation to the calendar border.

Month	Integer

Contains the currently selected calendar month.  Values will range from 1 to 12.

MonthNames	TStringList

Use this property to change the text for the month names displayed in the title bar.  (see International Support)

ReadOnly	Boolean

Set this to True to turn off mouse input over the day cells, and the left and right arrow key input.  The control bar still operates as do the page up, page down, up arrow and down arrow keys (see Keyboard Control).  This is normally used to present users with a "month view" upon which custom paint work has been done (see GetDayCellRect).  Setting this property to True will also disable the highlighting of a selected day.

ShowDayRow	Boolean

ShowDayRowBorder	Boolean

ShowHint	Boolean

These True/False properties will allow you to show (True) or not show (False) various calendar elements.

Style	Enumerated (csStandard, csOwnerDraw)

Set the style property to csOwnerDraw to obtain complete control of how the KSCalendar looks!  Setting the style to csOwnerDraw will result in the KSCalendar generating a OnDrawCell event everytime it needs a day cell painted.  You can use this method to do some very advanced custom painting.  See Owner Draw Information.

ThreeDLightColor	TColor

ThreeDShadowColor	TColor

Use these two color properties to select the light and shadow colors for 3D effects on the calendar.  Most of the time you would only change these colors if you have changed the surface color of the calendar itself (see CalendarColor).

TitleHeight	Integer

This is the height of the area of the rectangle that contains the month and year text.  You can increase this value if you plan to use a larger font for the either the month or year.

TitleStyle	Enumerated (tsNone, tsMonth, tsYear, tsMonthYear, tsFormatted)

Use this property to alter the style of the title bar (at top of calendar).  Display month, year, both or display the DateText property as the title!  Note:  When you set this style to tsFormatted the font that is used to display the title bar is FontMonth.

Weekday	Integer	Read Only

Contains the weekday (Sunday, Monday ...etc.)  of the currently selected date.  The integer value of this property can be interpreted as follows:  Sunday = 0, Monday=1, Tuesday=2 ... Saturday=6.

WeekNumber	Integer	Read Only

Contains the week number that the currently selected date falls into.  According to the International Standards Organization:

1.  A week is a period of seven days

2.  The first day of the week is a Monday

3.  Week number 1 is the first week of the year with 4 or more days

If you use this value a lot you might want to consider setting your WeekStart property to 1 (Monday).  This definition implies that you could have 53 weeks in a year and January 1,1995 is not necessarily in week 1.

WeekStart	Integer

Specifies the starting day of the week.  The integer value of this property can be interpreted as follows:  Sunday = 0, Monday=1, Tuesday=2 ... Saturday=6.

Year	Integer

Contains the currently selected calendar year.  Values will range from 1 to ?.


How Do I Purchase The KSCalendar?

KSCalendar introductory pricing ends on August 1, 1995!  Pick up the best calendar component for Delphi now and save!

What Do I Get?

You get the KSCalendar v1.0 and a voucher for a free upgrade (except shipping costs) for the next version released.  This help file is also included along with the source code for the Demo project demonstrating how to use the KSCalendar.  You also get lifetime technical support via Compuserve and a warm, fuzzy feeling from contributing to the growth of the Delphi 3rd party tools marketplace.

If you register the KSCalendar v1.0 Pro you will also receive all the source files for the component.

There are two ways to purchase KSCalendar:

Option 1   SWREG

KSCalendar v1.0 	Price: $27.95

On Compuserve 'GO SWREG' and register shareware #5997.  This results in Compuserve charging your account $27.95 and Compuserve then sends us your order.  All orders are filled the same day we get them from Compuserve.

KSCalendar v1.0 Pro 	Price: $49.95 (includes all KSCalendar source files)

On Compuserve 'GO SWREG' and register shareware #6052.  This results in Compuserve charging your account $49.95 and Compuserve then sends us your order.  All orders are filled the same day we get them from Compuserve.

Option 2   Direct

KSCalendar v1.0 	Price $24.95

KSCalendar v1.0 Pro 	Price $44.95 (includes all KSCalendar source files)

Print the following information on a sheet of paper:

Which KSCalendar Package (v1.0 or v1.0 Pro)

Your Name

Company

Your Job Title

Your E-Mail Address (please indicate if you want KSCalendar sent to you on-line)

Street Address

City, State

Zip

Daytime & Evening Phone Number

Send the above and the exact amount for the version you want (normal or Pro) to the address below.

If you are located in the state of Tennesee please add 8.5% sales tax.

Kinetic Software

8404 Swathmore Court

Knoxville, TN

37919

Acceptable forms of payment are:

- Personal or business check drawn on a US Bank in US funds

- Any type of money order (domestic or international) we can easily redeem in US funds

Make check or money order payable to Kinetic Software.


Events

All of KSCalendar's custom events are described below.  If you have any new events you would like to see let us know!!

Custom Event:

OnDateChange

This event is triggered whenever the day, month or year of the calendar are changed.  Use this event to track the users activities and to check for potential problems the user might encounter.

OnDrawCell

procedure(Control: TWinControl; Day: Integer; Rect: TRect; Coord: TPoint; State: Boolean) of object;

This event is generated if you have set the Style property to csOwnerDraw.  Custom drawing of the calendar should be done during the processing of this event.  The KSCalendar will give you a great deal of assistance in your painting process.  Day contains the day number that needs to be painted.  Rect will contain the day cell rectangle that your painting will occur within.  Coord will contain the row and column of the cell and State will contain whether the day is currently selected (True if selected / False if not selected).

OnFunction1Click

OnFunction2Click

These custom events are triggered when the control bar function buttons are pressed. For more information see the property ControlBarStyle.


Methods

All of KSCalendar's public methods are described below including their declaration in the original source Pascal code.  If you have any new methods you would like to see let us know!!

SetDate

Declaration:	procedure SetDate(NewDate: TDateTime);

Use this method to change the currently selected date of the calendar.  This method will result in a fairly optimized repaint of only those parts of the calendar that are effected.  This is the only way to change the calendar's date from code! (the Date property is read only)

You can use the KSCalendar to "crack" dates.  Use the SetDate method to set the appropriate date and then read off the values you are interested in from the properties Day, Month, Year, DayNumber, WeekNumber, Weekday etc.

GetDayCellRect

Declaration:	function  GetDayCellRect(ADay: Integer): TRect;

Use this powerful method to obtain the rectangle bounding a particular day.  If the day you pass in cannot be found on the currently displayed month this function will return a TRect with 0 for all its values.  Using this function in conjunction with the calendar's published Canvas property allows users to custom paint into the day cells.

Note: If you are going to custom paint on the calendar we recommend setting the ReadOnly property to True.  This will prevent the calendar's painting of the highlighted day from interfering.  In this way you can present a "month view" to the user with your custom paint work.  If you do not want to make the calendar read only then you can store the previously selected day and repaint it as well as the currently selected day every time the user selects a new day.

IsLeapYear

Declaration:	function  IsLeapYear(AYear: Integer): Boolean;

Use this method to  determine if a given year is a leap year.  Pass in the year and the method will return true if the year is a leap year and false if it is not.

DayNumberToDate

Declaration:	function DayNumberToDate(AYear,ADayNum: Integer): TDateTime;

This function will return a Delphi date (TDateTime) from a day number.  Because leap years screw thing up you have to pass in the year you are interested in as well as the day number.  If you pass in an illegal ADayNum (like 370) this method will return a -1.

DateToDayNumber

Declaration:	function DateToDayNumber(ADate: TDateTime): Integer;

This is the opposite of the above function.  Pass in a Delphi date and this method will return the day number.  This function of course takes leap years into consideration.

DaysInMonth

Declaration:	function DaysInMonth(AYear, AMonth: Integer): Integer;

Use this function to find out how many days (28,29,30 or 31) are in a given month.  Once again you must pass in the year and month because this method will take leap years into account.

DaysInYear

Declaration:	function  DaysInYear(AYear: Integer): Integer;

Use this function to find out how many days (28,29,30 or 31) are in a given month.  Once again you must pass in the year and month because this method will take leap years into account..

DaysRemaining

Declaration:	function  DaysRemaining(Index: Integer; ADate: TDateTime): Integer;

Use this function to find out how many days are remaining in a month or in a year.  To find the number of days left in a month call this method with Index=0.  To find the number of days left in a year call this method with Index=1.  Pass in the date you are interested in using ADate!

MonthStartsOn

Declaration:	function  MonthStartsOn(AYear,AMonth: Integer) : Integer;

This is an odd function (used internally so we published it...) that will tell you what day of the week a month starts on.  The integer return value can be interpreted as:  0=Sunday, 1=Monday, ... , Saturday=6.

DateToWeekNumber

Declaration:	function  DateToWeekNumber(ADate: TDateTime): Integer;

Use this function to find out what week number a particular date will fall into.  Week numbers returned can range from 1 to 53.

WeekNumberToDate

Declaration:	function WeekNumberToDate(AYear,AWeek,Day: Integer; var ADate: TDateTime): Boolean;

Use this function to calculate the day for a given week and weekday in a given year.  Pass in the year via AYear,  the week number via AWeek and the day of the week you are interested in via Day (remember 0=Sunday, 1=Monday ... 6=Saturday!).  Pass in the Date via ADate (the function will modify the date variable you pass in).

This function will return True if it made a successful calculation or False if it failed.

For example, if you wanted to calculate the date for the Wednesday of week 32 in 1995 you would use the following syntax:

if (KSCalendar1.WeekNumberToDate(1995,32,3,MyDateVar) then

  {success ... the date is stored in MyDateVar

else

  {failed ... the date stored in MyDateVar is meaningless (0/0/00)

This function will fail (return False) when the day you requested does not exist in the week you specified.  This will generally occur during week 1 or week 52-53.

GetDayForXY

Declaration:	function  GetDayForXY(X,Y: Integer): Integer;

This function will return the calendar day number at a specific X,Y location (relative to the top left corner of the calendar.  This is very useful when working with owner draw (see Style property) calendars.  Pass in the coordinates of a mouse click and this function will tell you which day was clicked on.  If the click is not on a valid day this function will return a 0.

DaysBetween

Declaration:	function  DaysBetween(ADate, BDate: TDateTime): Integer;

Use this method to calculate the number of days between two dates.  The order of the dates is important since this function will return the difference between the two dates as a positive or negative  integer.  If the two dates are identical this function will return a 0.  If BDate is before ADate this function will return a negative number.

NextDay

Declaration:	procedure NextDay;

Use this method to make the calendar increment visually to the next calendar day.

LastDay

Declaration:	procedure LastDay;

Use this method to make the calendar decrement visually to the previous calendar day.

NextMonth

Declaration:	procedure NextMonth;

Use this method to make the calendar increment visually to the next calendar month.

LastMonth

Declaration:	procedure LastMonth;

Use this method to make the calendar decrement visually to the previous calendar month.

NextYear

Declaration:	procedure NextYear;

Use this method to make the calendar increment visually to the next calendar year.

LastYear

Declaration:	procedure LastYear;

Use this method to make the calendar decrement visually to the previous calendar year.

Refresh

Declaration:	procedure Refresh;

Call this method to get the KSCalendar to completely redraw itself.

RefreshDays

Declaration:	procedure RefreshDays;

Call this method to get the KSCalendar to redraw only the day cells.  This can be useful to reduce flicker by not redrawing the entire calendar when only the days need to be updated.  Very useful when the calendar is in OwnerDraw mode (see Owner Draw Information)


Contacting Kinetic Software

We welcome any and all contact with our customers.  Please drop us a note with your feedback or questions!

You can contact Kinetic Software via:

Compuserve Address: 	102065,563

Internet Address: 	102065.563@Compuserve.Com

Mail:	Kinetic Software

 	8404 Swathmore Court

Knoxville, TN

37919


Keyboard Control

The KSCalendar can be fully controlled from the keyboard:

Key	Action

Page Up	Last Year

Page Down	Next Year

Up Arrow	Last Month

Down Arrow 	Next Month

Left Arrow 	Last Day

Right Arrow	Next Day

These key presses actually end up calling the corresponding KSCalendar public methods (LastYear, NextYear etc.)


International Support

To achieve internationalization all you have to do is enter the month names and day names for the target language as well as control bar hints (if you are using the control bar).  Theoretically the KSCalendar can support any language that uses alphanumeric numbers (1,2,3 etc).

The KSCalendar achieves full international support by publishing all the strings it uses internally as TStringList properties.  These properties are as follows:

Property	Required Number of Strings

ControlBarHintText	6

DayTitles	7

MonthNames	12

You can modify these properties at design time (via the TStringList property editor) or at run time (see the source file DEMO.PAS for an example).  If you enter more than the required number of strings the KSCalendar will ignore the extra strings.

By default the KSCalendar is English.


Owner Draw Information

As always if you have any comments on the owner draw functionality let us know!

The KSCalendar uses a powerful Owner Draw paradigm (similar to Delphi's owner draw list boxes) to give developer's almost unlimited freedom in designing their applications.  To make the KSCalendar owner drawn you must do two things:

1.	Set the Style property to csOwnerDraw (the default is csStandard).

2.	Supply painting logic in the OnDrawCell event.

Once you have done this the KSCalendar will generate OnDrawCell events for each day cell it requires painted.  You become responsible for painting everything within the day cell, including the actual day number (if you want it there).

The KSCalendar provides a great deal of assistance to you.  Lets look at the header for OnDrawCell event handler:

procedure TForm1.KSCalendarDrawCell(Control: TWinControl; Day: Integer; Rect: TRect; Coord: TPoint; State: Boolean);

The parameters passed to the event handler should provide all the information you require to accomplish your painting:

Parameter	Description

Control	The handle to the KSCalendar

Day	The day number (1 to 31) that is being painted

Rect	The rectangle bounding the day cell

Coord	The column (X) and the row (Y) of the cell being painted

State	The state of the cell being painted (True=selected, False=unselected).

For more information on how to build an owner draw KSCalendar refer to the source code of the DEMO project supplied with KSCalendar!


Public Properties

The following public properties facilitate access to the buttons (TSpeedButtons) on the control bar:

property  BLastMonth: TSpeedButton read FLMButton write FLMButton;

property  BLastYear: TSpeedButton read FLYButton write FLYButton;

property  BNextMonth: TSpeedButton read FNMButton write FNMButton;

property  BNextYear: TSpeedButton read FNYButton write FNYButton;

property  BFunction1: TSpeedButton read FFunc1 write FFunc1;

property  BFunction2: TSpeedButton read FFunc2 write FFunc2;

For example, to change the number of glyphs (NumGlyphs) property of the Function1 and Function2 buttons you would use the following syntax:

KSCalendar1.BFunction1.NumGlyphs: = 2;

KSCalendar1.BFunction2.NumGlyphs: = 2;

Other speedbutton properties like Visible, Caption or Font can be set in a similar manner.